Skip to content

Implement wtcli, an application to query details about an existing Terminal instance - #20461

Open
PankajBhojwani wants to merge 27 commits into
mainfrom
dev/pabhoj/wtcli
Open

Implement wtcli, an application to query details about an existing Terminal instance#20461
PankajBhojwani wants to merge 27 commits into
mainfrom
dev/pabhoj/wtcli

Conversation

@PankajBhojwani

@PankajBhojwani PankajBhojwani commented Jul 22, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary of the Pull Request

Implements wtcli, a new command-line client for Windows Terminal Protocol: a local COM control surface that lets external processes inspect and drive a running Windows Terminal instance. It provides a tmux-style command vocabulary for the terminal.

wtcli currently exposes 9 commands:

  • Inspect: list-windows (lsw), list-tabs (lst), list-panes
    (lsp), active-pane, pane-status
  • Mutate: new-tab (newt), split-pane (splitp), kill-pane
    (killp), focus-pane (focusp)

Every command supports --json for machine-readable output, otherwise results are rendered as human-readable output.

Detailed Description of the Pull Request / Additional comments

A client activates the server directly with CoCreateInstance using a per-brand CLSID (Release/Preview/Canary/Dev), and issues typed commands.

Components:
1. wtcli.exe: the CLI client (src/tools/wtcli/)
The user-facing tool. Parses subcommands, activates the protocol server and calls the interface methods.

2. ITerminalProtocol: the classic-COM interface (src/host/proxy/ITerminalProtocol.idl)
The contract between client and Terminal. A classic-COM interface marshaled by the MIDL proxy/stub in OpenConsoleProxy.dll. Scalar arguments stay typed; every complex result crosses the boundary as a JSON BSTR.

3. TerminalProtocolComServer: (src/cascadia/WindowsTerminal/)
Implements ITerminalProtocol inside WindowsTerminal.exe.

4. TerminalPage protocol bridge (src/cascadia/TerminalApp/TerminalPage.Protocol.cpp)
The UI-thread methods that query and mutate live terminal state (tabs, panes, process status) and return typed results.

5. TerminalProtocol shared library (src/cascadia/TerminalProtocol/)
Hosts the shared WinRT struct types (WindowInfo, TabInfo, PaneInfo, etc) consumed in-process by both the page bridge and the server. Also provides ProtocolParsing.h, a header of parsing helpers (ParseSplitDirection) shared by the server and the fuzzer.

6. Protocol fuzzer (src/cascadia/TerminalProtocol/ft_fuzzer/)
A LibFuzzer harness targeting the parsing function (ParseSplitDirection).

Validation Steps Performed

In a dev build of terminal, all 9 of the commands work

PR Checklist

  • Closes #xxx
  • Tests added/passed
  • Documentation updated
    • If checked, please file a pull request on our docs repo and link it here: #xxx
  • Schema updated (if necessary)

github-advanced-security[bot]
github-advanced-security Bot found potential problems Jul 22, 2026
View reviewed changes

@github-advanced-security github-advanced-security AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

check-spelling found more than 20 potential problems in the proposed changes. Check the Files changed tab for more details.

@github-actions

This comment has been minimized.

Sign in to view
@PankajBhojwani
PankajBhojwani marked this pull request as ready for review July 23, 2026 17:46
@github-actions

This comment has been minimized.

Sign in to view
@github-actions

This comment has been minimized.

Sign in to view
lhecker
Leonard Hecker (lhecker) reviewed Aug 18, 2026
View reviewed changes

@lhecker Leonard Hecker (lhecker) left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

BTW if we plan to just upstream this existing (?) code, I'm fine with just noting down some nits. Otherwise, I have some ideas how to improve it, like the STA/MTA thing.

Comment thread src/tools/wtcli/main.cpp

// Derive a per-install-path CLSID using the same v5 UUID formula as the server,
// so that unpackaged/portable clients find the correct matching server instance.
static GUID _portableClsid(const GUID& brandClsid)

@lhecker Leonard Hecker (lhecker) Aug 18, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we put these functions into src/types? We got CreateV5Uuid there already and we could link wtcli with it.

Unless you want to keep it portable of course.

@PankajBhojwani PankajBhojwani Aug 27, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd prefer to have it be standalone if possible! But if there's strong feelings in the other direction I'm alright to change it

Comment thread src/cascadia/TerminalApp/TerminalPage.Protocol.cpp
Comment thread src/cascadia/WindowsTerminal/TerminalProtocolComServer.cpp Outdated

// Register the COM class factory on a dedicated MTA thread so that
// incoming COM calls are dispatched to MTA worker threads rather than
// the STA/UI thread. This keeps long-running calls off the UI thread —

@lhecker Leonard Hecker (lhecker) Aug 18, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah here's the answer. But ...long-running? What calls do we foresee to be computationally expensive?

@PankajBhojwani PankajBhojwani Aug 27, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated the comment, previous one was outdated. The COM methods call .get() and that's the actual reason for the MTA thread.

@PankajBhojwani

PankajBhojwani commented Aug 27, 2026

Copy link
Copy Markdown
Contributor Author

BTW if we plan to just upstream this existing (?) code, I'm fine with just noting down some nits. Otherwise, I have some ideas how to improve it, like the STA/MTA thing.

It's mostly existing, I just stripped the stuff that we don't need here that are more agent CLI specific. Happy to hear about the improvements though! And maybe I can bring those downstream too.

zadjii-msft
Mike Griese (zadjii-msft) reviewed Sep 1, 2026
View reviewed changes
Comment thread src/host/proxy/ITerminalProtocol.idl Outdated
@carlos-zamora

Carlos Zamora (carlos-zamora) commented Sep 1, 2026 •
edited by PankajBhojwani
Loading

Copy link
Copy Markdown
Contributor

Feedback from 9/1 bug bash:

  • uh oh, needs client token check:
image
  • wtcli capturep doesn't set the output CP to utf-8 before emitting utf-8 text, resulting in this:
image
  • Should we have capturep? I feel that there is danger there
  • wtcli lsp returns 0 panes until i specify a tab/window, even though wtcli lst shows tabs in Current Window
  • wtcli lst -w foo doesn't support named windows :"(
  • actually, wtcli uses a different window ID mechanism than the rest of terminal... that's kinda worrying actually (DH. MG:+1)
  • when running unpackaged, the [wtcli] WT_COM_CLSID not set. Must run inside an Intelligent Terminal pane. error message most definitely shouldn't mention Intelligent Terminal
    • MG: I'm a big dumb and was using the wtcli from the path not the cwd
  • wtcli args are different from wt args (shouldn't they be largely the same EXCEPT for the new ones? or can they not be?)
  • wtcli should support /? to be like other windowsy things
  • we don't need to support / OVERALL, but /? is a windows standard (alas)
  • split-pane alias is splitw. Should it be splitp?
  • new-tab alias is neww. Should it be newt?
  • Idea: can/should we gate some functionality behind "enable debugging features"?

@microsoft-github-policy-service microsoft-github-policy-service Bot added the Needs-Author-Feedback The original author of the issue/PR needs to come back and respond to something label Sep 1, 2026
@microsoft-github-policy-service microsoft-github-policy-service Bot removed the Needs-Author-Feedback The original author of the issue/PR needs to come back and respond to something label Sep 1, 2026
@microsoft-github-policy-service microsoft-github-policy-service Bot added Needs-Author-Feedback The original author of the issue/PR needs to come back and respond to something and removed Needs-Author-Feedback The original author of the issue/PR needs to come back and respond to something labels Oct 14, 2026
@microsoft-github-policy-service microsoft-github-policy-service Bot added the No-Recent-Activity This issue/PR is going stale and may be auto-closed without further activity. label Oct 21, 2026
@microsoft-github-policy-service

microsoft-github-policy-service Bot commented Oct 21, 2026

Copy link
Copy Markdown
Contributor

This pull request has been automatically marked as stale because it has been marked as requiring author feedback but has not had any activity for 7 days. It will be closed if no further activity occurs within 7 days of this comment.

@microsoft-github-policy-service microsoft-github-policy-service Bot added Needs-Author-Feedback The original author of the issue/PR needs to come back and respond to something and removed Needs-Author-Feedback The original author of the issue/PR needs to come back and respond to something No-Recent-Activity This issue/PR is going stale and may be auto-closed without further activity. labels Oct 21, 2026
@microsoft-github-policy-service microsoft-github-policy-service Bot added Needs-Author-Feedback The original author of the issue/PR needs to come back and respond to something and removed Needs-Author-Feedback The original author of the issue/PR needs to come back and respond to something labels Oct 22, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@lhecker Leonard Hecker (lhecker) lhecker left review comments
@zadjii-msft Mike Griese (zadjii-msft) zadjii-msft left review comments
+1 more reviewer
@github-advanced-security github-advanced-security[bot] github-advanced-security[bot] left review comments
Reviewers whose approvals may not affect merge requirements

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

zBugBash-Consider

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@PankajBhojwani @carlos-zamora @lhecker @zadjii-msft @github-advanced-security